Loops

Loops allow a workflow to repeat an operation or group of operations while a runtime decision indicates that another iteration should occur. Loops are useful when the same workflow logic must execute repeatedly for a collection, batch, polling process, iterative calculation, or other intentional repeated operation. The exact public API for defining workflow loops should be taken from the installed BindAI implementation.

What Is a Loop?

A loop creates repeated execution within a workflow. Conceptually:

Loop
  |
  v
Evaluate Decision
  |
  +-- Continue --> Loop Body
  |                  |
  |                  +----> Loop
  |
  +-- Stop -------> Exit

The loop decides whether another iteration should execute. After the loop body completes, execution can return to the loop decision.

Why Use Loops?

Loops are useful when the same workflow logic must execute repeatedly. Common examples include:

Processing collections
Processing batches
Polling external systems
Waiting for background operations
Repeated validation
Processing paginated results
Performing repeated calculations
Incremental synchronization

Without loop behavior, repeated workflow logic would need to be duplicated or manually represented through graph cycles.

Loop Execution Flow

A typical loop follows this pattern:

Evaluate Decision
      |
  +---+---+
  |       |
Continue  Stop
  |       |
  v       v
Body     Exit
  |
  v
Update State
  |
  +------> Evaluate Decision

When the continuation decision is true, the workflow executes the loop body. After the body completes, the workflow evaluates the decision again. When the continuation decision becomes false, execution leaves the loop. The exact mechanics depend on the workflow execution implementation.

Loop State

Loops normally depend on information that changes as execution progresses. For example:

Initialize Position
        |
        v
Evaluate Position
        |
        v
Process Item
        |
        v
Advance Position
        |
        +----> Evaluate Position

The loop body must make progress toward its terminating state. If the state used to determine continuation never changes, the workflow may continue indefinitely.

Loop Body

The loop body contains the operations performed during one iteration. For example:

Loop
  |
  v
Agent
  |
  v
Tool
  |
  v
Update State
  |
  +----> Loop

A loop body can contain multiple operations. Depending on the workflow, those operations may include:

Agents
Tools
Conditions
Knowledge retrieval
Memory operations
External integrations
Validation
Data processing

The body should remain focused on the work required for one iteration.

Loop Exit

Every loop should have a clear exit path. Conceptually:

Loop Decision
   |
   +-- Continue --> Body --> Loop
   |
   +-- Stop -----> Exit

The exit path allows downstream workflow operations to continue after iteration is complete. A loop without a reachable exit can cause an unbounded workflow execution.

Loop Decisions

The continuation decision determines whether another iteration should occur. Conceptually:

Current Workflow State
        |
        v
Continuation Decision
     /         \
   True        False
    |            |
    v            v
  Body          Exit

The decision can depend on values produced by previous workflow operations. For example, a workflow may continue while:

More items remain
A task is not complete
A validation condition has not been satisfied
Additional pages are available
A synchronization process still has work

The exact decision API should follow the implemented workflow engine.

Example: Processing a Collection

A common loop pattern processes items one at a time.

Initialize Items
      |
      v
    Loop
      |
      v
Process Current Item
      |
      v
Advance Position
      |
      +------> Loop

Conceptually, the workflow maintains:

items
position

The continuation decision checks whether another item remains. For example:

position < number of items

The body processes the current item and advances the position.

Example: Polling an External Service

A loop can repeatedly check the state of an asynchronous operation.

Check Status
     |
     v
Continue?
  /       \
Yes        No
 |          |
 v          v
Wait       Exit
 |
 +----> Check Status

The workflow can retain the current operation status and evaluate it after each polling interval. For production polling workflows, include an appropriate delay or backoff mechanism so that the external service is not queried continuously. A maximum polling duration or timeout can also prevent an external operation from keeping the workflow active indefinitely.

Example: Batch Processing

Loops can process batches incrementally.

Load Batch
    |
    v
  Loop
    |
    v
Process Batch
    |
    v
Load Next Batch
    |
    +------> Loop

The continuation decision determines whether another batch remains. This approach can prevent a large collection from being processed in one oversized workflow operation.

Example: Pagination

A workflow can repeatedly request pages of data.

Request Page
     |
     v
Process Results
     |
     v
More Pages?
   /       \
 Yes        No
  |          |
  v          v
Next Page   Exit
  |
  +----> Process Results

The workflow can use pagination information returned by the external service to determine whether another iteration is required.

Example: Repeated Validation

A workflow may repeat validation until a desired state is reached.

Prepare Data
     |
     v
Validate
     |
     v
Valid?
 /     \
Yes     No
 |       |
 v       v
Exit   Update Data
          |
          +----> Validate

The loop should have a reliable termination mechanism when the data or external state is unpredictable.

Loops vs Retry

Loops and retries both involve repeated execution, but they solve different problems.

Loop	Retry
Repeats intentional workflow logic	Repeats failed execution
Part of normal workflow design	Reliability mechanism
Usually controlled by runtime state	Triggered by failure
May process many iterations	Usually limited by attempts
Can represent business processes	Handles transient failures

Use a loop when repetition is part of the intended workflow behavior. Use retry when an operation fails and should be attempted again according to a reliability policy. A retry should not normally be implemented by wrapping every failure in a general-purpose workflow loop.

Loops with Conditions

Conditions can be used inside a loop.

Loop
  |
  v
Agent
  |
  v
Condition
 /       \
Continue  Stop
  |        |
  v        v
Update    Exit
State
  |
  +----> Loop

The loop controls repetition. The condition controls a decision within the iteration. This separation is useful when each iteration contains several possible outcomes.

Loops with Agents

An agent can participate in each loop iteration. For example:

Loop
  |
  v
Agent
  |
  v
Evaluate Result
  |
  v
Update State
  |
  +----> Loop

This can be useful for iterative analysis, classification, planning, or processing of multiple items. The workflow should still define clear termination behavior independently of the model’s output.

Loops with Tools

Tools are useful when each iteration performs deterministic work.

Loop
  |
  v
Tool
  |
  v
Tool Result
  |
  v
Update State
  |
  +----> Loop

Examples include:

Processing records
Calling an API for each item
Writing application data
Performing calculations
Synchronizing external resources

Tool failures should follow the workflow’s error and retry policies.

Loops with Knowledge

Knowledge retrieval can be performed during repeated processing. For example:

Loop
  |
  v
Retrieve Knowledge
  |
  v
Process Results
  |
  v
Next Item
  |
  +----> Loop

This can be useful when each item requires separate retrieval or contextual analysis. Knowledge remains responsible for retrieval, while the workflow controls iteration.

Loops with Memory

Memory can also participate in iterative workflows. For example:

Read Memory
    |
    v
Process Item
    |
    v
Update Memory
    |
    +----> Loop

Memory can preserve information beyond the immediate operation. Workflow state, meanwhile, should carry information required for the current execution process.

Nested Loops

Loops can be combined with other loops. For example:

Outer Loop
    |
    v
Inner Loop
    |
    v
Process
    |
    +----> Inner Loop

A common use case is hierarchical data:

For each customer
    |
    +--> For each order
             |
             +--> Process Order

Nested loops can be useful, but excessive nesting makes workflows harder to understand and debug. When nested iteration becomes complex, consider splitting the process into smaller workflow stages.

Avoiding Infinite Loops

Every loop needs a reliable path toward termination. For example:

Counter
  |
  v
Evaluate
  |
  v
counter < limit
  |
  v
Process
  |
  v
counter += 1
  |
  +----> Evaluate

The loop body changes the state used by the continuation decision. Eventually:

counter >= limit
      |
      v
    Exit

If the state never changes, the continuation decision may remain true indefinitely. Good loop design therefore requires:

A clear termination condition
State that changes during execution
Measurable progress toward termination
Appropriate safeguards for long-running operations

Maximum Iterations

For loops that depend on external systems or unpredictable data, a maximum iteration limit can provide an additional safety mechanism. Conceptually:

Loop
 |
 +--> Decision
 |
 +--> Iteration Count
          |
          +--> Limit reached → Exit / Error
          |
          +--> Limit not reached → Continue

This prevents unexpected state from causing unbounded workflow execution. The exact configuration mechanism should follow the implemented BindAI workflow API.

Timeouts and Cancellation

Long-running loops should also consider execution limits. Conceptually:

Loop
 |
 +--> Iteration Limit
 |
 +--> Timeout
 |
 +--> Cancellation
 |
 +--> Normal Exit

These safeguards are particularly important for:

External polling
Large collections
Untrusted input
Slow integrations
Long-running agent operations

The exact timeout and cancellation APIs depend on the workflow implementation.

Error Handling

A failure inside a loop body should follow the workflow’s configured error-handling behavior. Possible strategies include:

Loop Body Failure
      |
      +--> Stop Workflow
      |
      +--> Retry Failed Operation
      |
      +--> Error Path
      |
      +--> Continue

The correct behavior depends on the operation and application requirements. For transient failures, use retry policies rather than treating every retry as a new business-level loop iteration.

Loop Progress

A useful loop should make measurable progress. For example:

Iteration 1
   |
   v
Process Item 1
   |
   v
Iteration 2
   |
   v
Process Item 2
   |
   v
Iteration 3

Progress can be represented by:

An item position
A page number
A batch identifier
A task status
A completion flag
Remaining work

Making progress explicit helps prevent accidental non-termination.

Testing Loops

Loop behavior should be tested across several scenarios.

Zero iterations

The continuation decision is initially false.

Loop
  |
  v
False
  |
  v
Exit

The loop body should not execute.

One iteration

The decision is initially true but becomes false after one iteration.

Loop
  |
  v
True
  |
  v
Body
  |
  v
Loop
  |
  v
False
  |
  v
Exit

Multiple iterations

The decision remains true for several iterations before becoming false.

Non-terminating state

The continuation decision never becomes false. The workflow should have an appropriate safeguard such as:

Maximum iterations
Timeout
Cancellation
External execution limit

Loop Observability

Long-running loops should be observable. Useful information includes:

Current iteration
Progress
Start time
Duration
Current operation
Failure count
Retry count
Termination reason

This information makes it easier to diagnose workflows that take longer than expected or fail during a particular iteration. The exact observability APIs should follow the BindAI implementation.

Loop Design Pattern

A reliable loop generally follows this pattern:

Initialize State
      |
      v
Loop Decision
   /       \
 Stop     Continue
  |          |
  v          v
Exit      Execute Body
             |
             v
         Update State
             |
             +----> Loop Decision

The important property is that the body changes the state used by the continuation decision. That creates measurable progress toward termination.

Common Use Cases

Loop behavior is useful for:

Collection processing
Batch processing
Pagination
Polling external services
Repeated validation
Incremental synchronization
Waiting for state changes
Iterative analysis
Multi-step record processing
Repeated application operations

Best Practices

Define a clear termination condition.
Make sure the loop can eventually exit.
Update the state used by the continuation decision.
Keep loop bodies focused.
Avoid unnecessary nested loops.
Use retry policies for transient execution failures.
Consider maximum iteration limits.
Add delays or backoff when polling external services.
Use timeouts for potentially unbounded execution.
Support cancellation for long-running workflows.
Monitor progress in production workflows.
Test zero, one, multiple, and non-terminating scenarios.
Keep business logic separate from orchestration logic.

Current BindAI Scope

BindAI supports loop-based workflow orchestration as part of its workflow capabilities. Loop behavior can be used to coordinate:

Repeated agent execution
Repeated tool execution
Collection processing
Batch processing
Conditional repetition
External polling
Iterative validation
Multi-step repeated operations
Retry and reliability patterns

The exact public API for defining loops should be verified against the installed BindAI workflow implementation. This document intentionally does not assume specific APIs such as:

builder.loop(...)
WorkflowLoop(...)
LoopNode(...)
WorkflowContext(...)

or a particular predicate signature unless those APIs are verified in the current release.

API Accuracy

The workflow concept described here is iterative execution. Implementation details such as:

Loop classes
Builder methods
Predicate signatures
Loop-body registration
Exit-path registration
Iteration limits
Timeout configuration
Cancellation behavior
Loop serialization

should only be documented as public BindAI APIs when they are present in the implementation and covered by tests. This keeps the documentation synchronized with the actual workflow engine.

Summary

Loops allow BindAI workflows to repeat intentional workflow logic. A typical loop follows:

Decision
   |
   +-- Continue → Body → Update State → Decision
   |
   +-- Stop ----> Exit

Loops are useful for collections, batches, pagination, polling, iterative validation, synchronization, and other repeated processes. The loop body should make measurable progress toward termination, while maximum iterations, timeouts, and cancellation can protect against unbounded execution. Loops and retries should remain conceptually separate:

Loops repeat intentional workflow behavior; retries recover from execution failures.

Specific loop APIs should only be documented after they are verified against the current BindAI implementation and tests.

​Loops

​What Is a Loop?

​Why Use Loops?

​Loop Execution Flow

​Loop State

​Loop Body

​Loop Exit

​Loop Decisions

​Example: Processing a Collection

​Example: Polling an External Service

​Example: Batch Processing

​Example: Pagination

​Example: Repeated Validation

​Loops vs Retry

​Loops with Conditions

​Loops with Agents

​Loops with Tools

​Loops with Knowledge

​Loops with Memory

​Nested Loops

​Avoiding Infinite Loops

​Maximum Iterations

​Timeouts and Cancellation

​Error Handling

​Loop Progress

​Testing Loops

​Zero iterations

​One iteration

​Multiple iterations

​Non-terminating state

​Loop Observability

​Loop Design Pattern

​Common Use Cases

​Best Practices

​Current BindAI Scope

​API Accuracy

​Summary